<!--
 
 This file is part of EspGrid.  EspGrid is (c) 2012,2013 by David Ogborn.
 
 EspGrid is free software: you can redistribute it and/or modify
 it under the terms of the GNU General Public License as published by
 the Free Software Foundation, either version 3 of the License, or
 (at your option) any later version.
 
 EspGrid is distributed in the hope that it will be useful,
 but WITHOUT ANY WARRANTY; without even the implied warranty of
 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License
 along with EspGrid.  If not, see <http://www.gnu.org/licenses/>.
 
 -->

<html>
    <head>
        <title>EspGrid OSC specification</title>
    </head>
    <body>

<h1>OSC issued by EspGrid</h1>
        
    <ul>
        
    <li>/clock/offset/r [offset]<br/>
        where:<br/>
        offset = (EspGrid synchronized time) - (local system clock relative to UNIX epoch starting Jan 1 1970) [float64]<br/>
        This message is part of the emerging TOPLAP clock protocol, and is only issued in response to receiving /clock/offset/q.  The response message is sent to a specific host and port.  If /clock/offset/q has no arguments, then the response is sent to the IP address and port deduced from the incoming message.  If /clock/offset/q has one argument, that is interpreted as a port, and the response is sent to that port on whichever host is deduced from the incoming message.  If /clock/offset/q has two arguments, then they are assumed to be the port and host (in that order) to which the response should be sent.<br/>
    </li>
    
    <li>/esp/tempo/r [on] [bpm] [time] [n] [length]<br/>
        where:<br/>
        on = tempo is on or paused [0 or 1, int32]<br/>
        bpm = beats per minute [float64]<br/>
        time = the logical time (EspGrid sync time) at which a specific beat from this metre occurs [float64]<br/>
        n = the number of this beat (total accumulated beats before that beat) [int32]<br/>
        length = the number of beats in a bar<br/>
        The specification of this message is expected to evolve pending the TOPLAP clock protocol discussion.  Like /clock/offset/r this message is request-driven, and is issued only in reponse to /esp/tempo/r.  Like /clock/offset/q, no arguments to /esp/tempo/q results in a response to the port and host deduced from the source of the request, one argument explicitly sets a port (with the host deduced), and two arguments explicitly sets the port and host (in that order) for the response.<br/></li>

    <li>/esp/beat [n] [l] [d]<br/>
    where:<br/>
    n = the number of the beat, i.e. 1 for the first beat of a bar [int32]<br/>
    l = the number of beats in a bar [int32]<br/>
    d = the duration of a beat in seconds [float32]<br/>
    </li>
   
    <li>/esp/chat/receive [remainder of items are text of message]</li>
    
    <li>plus any user-specified messages created with the /esp/msg/* operations described below (in OSC control)</li>
        
    </ul>
    

<h1>OSC Control</h1>
    
        <div>In some cases, it is advantageous to control the grid software from other software.  For example, a Max patch might be created to turn beat generation on, then change the tempo in a specific way at specific times.  Additionally, EspGrid can be used to broadcast arbitrary OSC messages at specific synchronized times (ranging from immediately to in the distant future).  Here is a complete list of the OSC messages to which the EspGrid application responds.  These should be sent from a local application to port 5510:</div>

<ul>
    <li>/esp/beat/on [0 or 1 to turn beat off or on respectively, int32]</li>
    <li>/esp/beat/tempo [tempo in beats per minute, float32/64]</li>
    <li>/esp/beat/cycleLength [number of beats in each bar, type: int32]</li>
    <li>/esp/chat/send [remainder of items are text of message to send]</li>
    <li>/esp/codeShare/post [title] [remainder of items are text of code to be shared]</li>
    <li>/esp/msg/now [/some/other/oscAddress] [rest of parameters to OSC message] (the specified OSC message is sent immediately to everyone on the grid)</li>
    <li>/esp/msg/soon [/some/other/oscAddress] [rest of parameters to OSC message] (the specified OSC message is schedule on every computer a very short moment from now - and thus can be synchronized)</li>
    <li>/esp/msg/future [timeIncrement in seconds, type: float32/64] [/some/other/oscAddress] [rest of parameters to message] (the specified OSC message is sceheduled [timeIncrement] seconds into the future, synchronized on all machines running EspGrid</li>
    <li>/esp/msg/nowStamp... (same as /esp/msg/now except that a timestamp (from the issuing computer) is added to msg received by all machines)</li>
    <li>/esp/msg/soonStamp... (same as /esp/msg/soon except that the scheduled time of the message is included in the msg received as first parameter)</li>
    <li>/esp/msg/futureStamp... (same as /esp/msg/future except that the scheduled time of the message is included in the msg received as first parameter)</li>
    
    <li>/esp/bridge/localGroup [string] (set the name of the local group when making a WAN bridge)</li>
    <li>/esp/bridge/localAddress [string] (set the address of this computer on the WAN for receiving bridge connections)</li>
    <li>/esp/bridge/localPort [string] (set the port on which this computer will receive WAN bridge connections - 5508 recommended)</li>
    <li>/esp/bridge/remoteAddress [string] (set the IP address of the remote group when making a bridge)</li>
    <li>/esp/bridge/remotePort [string] (set the port which the remote group has opened for a bridge - 5508 recommended)</li>
    
</ul>
        
        <div>In addition, the user defaults/preferences of the application can be changed via OSC, by sending messages as follows:</div>
        
<ul>
    <li>/esp/name [string] (change your name on the grid)</li>
    <li>/esp/machine [string] (change this machine's name on the grid)</li>
    <li>/esp/broadcast [string] (change the local network broadcast address)</li>
    <li>/esp/clockMode [0-2] (change the clock mode)</li>
    <li>/esp/connectToMax [0 or 1] (connect to Max)</li>
    <li>/esp/connectToChuck [0 or 1] (connect to Chuck)</li>
    <li>/esp/connectToPD [0 or 1] (connect to PD)</li>
    <li>/esp/connectToSupercollider [0 or 1] (connect to Supercollider)</li>
    <li>/esp/customAddress1 [string] (custom connection to an application via UDP)</li>
    <li>/esp/customPort1 [int] (the port for the above custom connection via UDP)</li>
    <li>/esp/customAddress2 [string] (custom connection to an application via UDP)</li>
    <li>/esp/customPort2 [int] (the port for the above custom connection via UDP)</li>
    <li>/esp/customAddress3 [string] (custom connection to an application via UDP)</li>
    <li>/esp/customPort3 [int] (the port for the above custom connection via UDP)</li>
    <li>/esp/customAddress4 [string] (custom connection to an application via UDP)</li>
    <li>/esp/customPort4 [int] (the port for the above custom connection via UDP)</li>
</ul>

    <div>EspGrid is gradually adopting the emerging TOPLAP clock protocols.  In order for a language-side client to receive a /clock/offset/r message (see above) with the offset value that, when added to the system clock time, synchronizes with EspGrid logical time, the language-side client sends EspGrid the message /clock/offset/q.  The /clock/offset/r message is not sent on any automatic schedule by EspGrid - it is only sent in response to a /clock/offset/q message.  Similarly, synchronized tempo information (that can be used to generate highly accurate tempo streams within a language client) is accessed by issuing the /esp/tempo/q query, and receiving an /esp/tempo/r response.</div>
    
</body>
</html>

